Same shape as P2.1 (kafka), scoped to what's testable without a real
NATS broker:

  - init() side effect (RegisterDestination("nats", ...))
  - constant values pin (natsReconnectsCst, natsTimeoutCst)
  - Close-on-nil-client safety (must not panic)
  - "nats:" scheme prefix stripping via a net.Listen("tcp", ":0")
    fake server — observes that the dial reaches the stripped
    host:port within natsTimeoutCst + 2s grace
  - 16-goroutine race test of Close

Out of scope (real broker required, covered by microvm lifecycle):
  - Send/Publish flow
  - FlushTimeout-on-Close behaviour
  - newNATSDest's RetryOnFailedConnect retry semantics

Verified:
  - go test -tags dest_nats -race ./pkg/xtcp/ → PASS
  - nix build .#test-go-flavor-nats → PASS
  - destinations_nats.go now appears in coverage.out
  - pkg/xtcp coverage under dest_nats: 81.3%

Same shape as P2.1/P2.2, scoped to what's testable without a real
nsqd. Conveniently nsq.NewProducer is lazy at construction time
(only Publish actually dials), so the constructor + Close paths
unit-test cleanly:

  - init() side effect (RegisterDestination("nsq", ...))
  - newNSQDest table (positive/boundary + corner/adversarial that
    document nsq.NewProducer's permissive addr handling)
  - Close-on-nil-producer safety
  - Send against unreachable broker: verifies the err counter
    increments + Send returns 0, err
  - "nsq:" scheme stripping via fake TCP listener (observes dial
    reaches the stripped host:port when Publish triggers connect)
  - 16-goroutine race test of Close

Out of scope (real nsqd required, covered by microvm lifecycle):
  - Successful Send / Publish
  - producer.Stop() flush semantics on a connected producer

Verified:
  - go test -tags dest_nsq -race ./pkg/xtcp/ → PASS
  - nix build .#test-go-flavor-nsq → PASS
  - destinations_nsq.go now appears in coverage.out
  - pkg/xtcp coverage under dest_nsq: 81.8%

Same shape as P2.1/P2.2/P2.3, scoped to what's testable without a
real Valkey/Redis-protocol server:

  - init() side effect (RegisterDestination("valkey", ...))
  - constants (ping timeout, IO timeout, max idle conns)
  - Close-on-nil-client safety
  - newValKeyDest against unreachable URL: returns err within
    valkeyPingTimeoutCst + 1s grace
  - newValKeyDest with empty addr after prefix: also errs
  - 16-goroutine race test of Close-on-nil

Out of scope (real Valkey server required, covered by microvm
lifecycle): the happy-path Ping at construction, Send/Publish, real
Close on a connected client. Attempted a fake RESP server in this
test file but go-redis v9's HELLO + CLIENT SETINFO negotiation
makes hand-rolling a fake brittle across go-redis versions —
microvm integration is the right place for that.

Verified:
  - go test -tags dest_valkey -race ./pkg/xtcp/ → PASS
  - nix build .#test-go-flavor-valkey → PASS
  - destinations_valkey.go now appears in coverage.out
  - pkg/xtcp coverage under dest_valkey: 81.1%

Add a coverage-regression check to tools/quality-report/main.go:

  - new flags: -coverage-baseline <file>  (default empty = disabled)
                -coverage-max-drop <float> (default 0.5%)
  - new helper evaluateCoverageRatchet(): reads the baseline file via
    readCoverageBaseline() and compares to in.Coverage.Total; returns
    (msg, true) when the absolute drop exceeds maxDropAbs
  - runMain returns exit code 3 (distinct from emit-error code 2) on
    ratchet breach so callers can distinguish "report broken" from
    "report fine, just below the floor"

Missing or unparseable baseline file silently passes the check
(treated as "no baseline yet" — first run on a new branch).

docs/coverage-baseline.txt seeded with 88.0 — a conservative floor
below the current default-flavor total of 89.3% measured locally with
go test ./pkg/... ./tools/... ./cmd/... -coverpkg=…/pkg/…,/tools/…,
/cmd/…. Operator manually bumps this file when they intentionally
raise the floor (e.g. after a coverage push).

nix/quality-report/default.nix passes the new flags. The orchestrator
treats exit code 3 as a warning (markdown still emitted, exit
non-zero propagates to CI); any other non-zero exit aborts the
derivation as before.

New ratchet_test.go covers:
  - readCoverageBaseline: positive/negative/boundary/corner/adversarial
    (12 rows) — exercises plain float, %-suffix, whitespace, missing
    file, empty path, unparseable, negative value, giant value
  - evaluateCoverageRatchet: 11 rows pinning the exact drop math
    incl. the "exactly at grace" and "zero max drop = strict" cases
  - end-to-end runMain → exit 3 on breach + exit 0 on pass via
    synthetic raw-dir fixtures
  - 2 benchmarks

Verified:
  - go test ./tools/quality-report/ → PASS
  - nix build .#test-tools-quality-report → PASS
  - nix flake show evaluates cleanly

The previous `set +e ... go run ... ; set -e` dance failed to catch
the exit-3 ratchet code inside Nix's runCommand wrapper, so the
build script aborted before the `mkdir -p $out/raw; cp -r $RAW/...
$out/raw/` steps ran. Result: the store path was missing raw/,
coverage.html, bin/quality-report — only the markdown survived.

Replace with the `|| qr_rc=$?` idiom which works portably under
`set -eu` regardless of how the build wrapper sets shell options.
The WARNING echo now correctly fires on ratchet breach and the rest
of the script (raw/ + coverage.html + bin/) continues.

Also lower docs/coverage-baseline.txt from 88.0 → 86.0. The 88.0
seed reflected my local non-short measurement (89.3%); the Nix
sandbox runs `go test -short` which skips longer tests and measures
86.90%. Anchoring to 86.0 gives an honest floor for what the
quality-report can reliably measure.

Full quality-report run via `nix run .#update-quality-report` after
the per-flavor coverage merge + ratchet landed. Headlines:

  Coverage:  86.9% overall (Nix-sandbox -short measure; ratchet PASS
                            vs 86.0 baseline + 0.5 grace)
  - 17/23 packages ≥90%
  - 6/23 below 90%; biggest gap pkg/xtcp 77.3% — that's the per-flavor
    merge making the previously-invisible destinations_{kafka,nats,
    nsq,valkey}.go (each ~80%) count toward the package average for
    the first time. The drop is more honest measurement, not a
    regression.

  Findings: 70 (was 8 pre-wave)
  - 21× misspell — top contributor, almost all in the new test files
    I added across this wave (e.g. "advaserial" misspellings in test
    names + a few in code comments)
  - 16× gofmt — newly-added test files formatted by goimports rather
    than gofmt
  - synthRecommendations now flags this as "run `golangci-lint --fix`
    to auto-resolve ~55 quick-fixable findings"

The new gofmt/misspell findings are nuisance lint — not real issues
— and the `lint-fix` Nix app can clear most in one pass. Saving the
cleanup for a follow-up commit so the test commits stay focused.

Auto-formatted 16 files flagged by gofmt + golangci-lint's gofmt linter.
Mechanical change — only whitespace + import grouping. Tests pass
unchanged.

Auto-fix via `nix run .#lint-fix-one -- misspell`. Mechanical
US-English normalisation across the new test files; all tests pass
unchanged.

Address the manual lint findings from docs/quality-report.md that
`golangci-lint --fix` doesn't auto-resolve:

  cmd/xtcp2client/stream_helpers_test.go:
    gocritic/unlambda — replace
    `func() context.Context { return context.Background() }` with
    `context.Background` (same signature).

  cmd/xtcp2client/xtcp2client.go:
    exhaustive — switch on recvAction missing recvContinue case;
                 add explicit case with fall-through comment.
    gocritic/exitAfterDefer — log.Fatalf in pollMode meant
                 `defer ticker.Stop()` never ran; demote to
                 log.Printf + return so defers fire.

  pkg/io_uring/ring.go:
    staticcheck/ST1011 — rename closeDrainStepMs → closeDrainStep
    (time.Duration shouldn't carry unit suffix; same value).

  pkg/xtcp/netlinker_helpers_test.go:
    staticcheck/SA4004 — drop the `for _, e := range entries { ...
    break }` idiom that was unconditionally terminated after one
    iteration. Read entries[0] directly.

  tools/quality-report/main_test.go:
    staticcheck/QF1001 — apply De Morgan's law to the !(A && B && C)
    assertion so the linter is happy.

  nix/tests/go-test-{flavors,per-package}.nix:
    nixfmt sweep — flat attrset → multi-line { x = { tags = ...; }; }
    form that nixfmt prefers.

All tests still pass.

Three new tests + two production var-lifts (production behavior
unchanged):

  cmd/xtcp2client/xtcp2client.go:
    Lift ResourceExhaustedSleepTime (30s) and JitterSleepMaxMs (10s)
    from const → var so tests can shrink them to microseconds and
    exercise the time.After branch of resourceExhaustedSleep without
    wall-clocking 30-40 seconds. Production code never mutates them.

  cmd/xtcp2client/stream_helpers_test.go:
    + TestResourceExhaustedSleep_liveCtxRunsFullSleep
       exercises the false-return path (sleep completes, ctx live)
       via shrunken base + jitter
    + TestResourceExhaustedSleep_debugLogPath
       covers the debugLevel>10 log emission
    + TestHandleRecvContinueErr_resourceExhaustedLiveCtxContinues
       drives the ResourceExhausted + live-ctx → continue branch of
       handleRecvContinueErr (was 75% covered → now 87.5%)
    + TestHandleRecvContinueErr_debugLogPath
       covers the debug-log gate

  cmd/xtcp2client/xtcp2client_test.go:
    + TestRunMain_pollModeCancellable — runs runMain with -poll on a
      pre-cancelled ctx so the `if *poll { pollMode(...) }` branch
      gets coverage (was 95.2% → now 100%).

resourceExhaustedSleep: 66.7% → 100%
runMain:                95.2% → 100%
handleRecvContinueErr:  75.0% → 87.5%
TOTAL:                  87.9% → 91.5% ✓ above 90%

Lift proto.Marshal as the marshalFn seam (var defaulting to
proto.Marshal). Two new tests exercise the previously-unreachable
error branches:

  + TestEncodeLengthDelimitedProtobufList_marshalErr — fake marshaller
    returns err → encodeLengthDelimitedProtobufList wraps + returns
    'error marshaling Record'
  + TestRunMain_encodeError — same fake marshaller, drives runMain
    → rc=1 + 'Error encoding' on stderr

encodeLengthDelimitedProtobufList: 85.7% → 100%
runMain:                           86.2% → 93.1%
TOTAL:                             86.4% → 93.2% ✓ above 90%

One new test (TestRunMain_kafkaMode) drives runMain through the
`if c.kafka { ... }` branch using a 2-second ctx timeout to
short-circuit destKafka's wg.Wait on Produce's callback (which would
otherwise wait for franz-go connection retries to exhaust).

  runMain:        76.7% → 93.0%
  primaryFunction: 86.7% → 93.3%
  TOTAL:           85.4% → 90.7% ✓ above 90%

  cmd/xtcp2client/xtcp2client.go
    gofmt sweep (leftover from L3 const-removal).

  cmd/kafka_to_clickhouse/kafka_to_clickhouse.go
    contextcheck: pass the caller's ctx into the deferred Flush
    context.WithTimeout instead of context.Background() so cancellation
    propagates correctly.

  pkg/xtcpnl/xtcpnl_fatalf_test.go
    unconvert: drop unnecessary int64() cast on tv.Sec
    (syscall.Timeval.Sec is already int64 on the build targets we
    actually compile for; the Usec cast stays because it's int32 on
    32-bit Linux).

  pkg/xtcp/ns_map_count.go
    unused: remove dead goRoutineReporterFrequency const (was never
    referenced after the F3 refactor split out tickers into vars).

Findings:  70 → 4 (only 3 below-90% coverage + 1 transient sandbox
test flake; the 5 lint findings cleaned up by L4 are gone)

Coverage table updates:
  cmd/clickhouse_protobuflist     86.4% → 93.2%
  cmd/kafka_to_clickhouse         85.4% → 90.7%
  cmd/xtcp2client                 88.4% → 91.5%
  (the L4 work also touched cmd/kafka_to_clickhouse + pkg/xtcp/
  ns_map_count.go but doesn't move coverage numbers materially)

The three remaining 'below-90%' packages all need real broker/syscall
fixtures (pkg/xtcp 77.3% — the destination flavor merge surfaced
broker-bound code; cmd/xtcp2_kafka_client 81.4% — pollLoop's
EachRecord closure body; tools/kafka_topic_reader 86.0% — same). All
covered by the microvm-lifecycle integration harness.

Lift the kgo.Client surface kafkaDest uses into a 5-method
kafkaProducer interface (Produce, Flush, Close, Ping, AllowRebalance).
*kgo.Client satisfies it via its concrete methods so production is
unchanged. d.client becomes kafkaProducer.

Add fakeKafkaProducer to destinations_kafka_test.go that records
calls + lets each test inject Produce / Flush / Ping errors and
control failFirstNPings for the retry-recovery path.

New tests under build tag dest_kafka:

  TestKafkaDest_Send_table          — positive / negative / boundary /
                                      corner / adversarial (6 rows);
                                      drives both timeout-set and
                                      timeout-unset paths
  TestKafkaDest_Send_debugLog       — debugLevel>10 branch
  TestKafkaDest_Close_table         — clean close + flush-err-still-closes
  TestKafkaDest_CloseNilClient      — nil-client safety
  TestKafkaDest_Close_debugLog      — debugLevel>10 branch
  TestPingKafkaWithRetries_table    — 5 rows: 1st-ping success,
                                      Nth-ping recovery, exhausted-retries,
                                      zero-retries, exact-boundary
  TestPingKafkaWithRetries_ctxCancelAbortsSleep
  TestPingKafkaWithRetries_debugLog

Per-function coverage on destinations_kafka.go:
  Send                   0%    → 96.2%
  Close                  0%    → 100%
  pingKafkaWithRetries   0%    → 100%
  pingKafka              0%    → 100%

Whole pkg/xtcp under dest_kafka: 76.7% → 80.1%

Lift the *nats.Conn surface natsDest uses into a 3-method
natsPublisher interface (Publish, FlushTimeout, Close). *nats.Conn
satisfies it; production unchanged.

New tests:
  TestNATSDest_Send_table        — positive / negative publish; verifies
                                   counter + last-subj match
  TestNATSDest_Send_debugLog
  TestNATSDest_Close_table       — clean close + flush-err-still-closes
  TestNATSDest_Close_debugLog

destinations_nats.go:
  Send  0% → 100%
  Close 0% → 100%

Whole pkg/xtcp under dest_nats: 81.6%

Lift the *nsq.Producer surface nsqDest uses into a 2-method
nsqProducer interface (Publish, Stop). *nsq.Producer satisfies it
via its concrete methods; production unchanged.

New tests:
  TestNSQDest_Send_table          — positive / negative
  TestNSQDest_Send_debugLog
  TestNSQDest_Close_stopsProducer

destinations_nsq.go:
  Send  0% → 100%
  Close 0% → 100%

Whole pkg/xtcp under dest_nsq: 81.5%

Lift the *redis.Client surface valkeyDest uses into a 3-method
valkeyPublisher interface (Publish, Ping, Close) — with flat error
returns instead of go-redis's *redis.IntCmd / *redis.StatusCmd
chains. A redisClientAdapter wraps the real *redis.Client into the
interface; newValKeyDest now constructs that wrapper. Production
behavior unchanged.

New tests:
  TestValkeyDest_Send_table      — positive / negative publish
  TestValkeyDest_Send_debugLog
  TestValkeyDest_Close_table     — clean + close-err
  TestValkeyDest_RedisClientAdapter_Close — pins adapter satisfies iface

destinations_valkey.go:
  Send  0% → 100%
  Close 0% → 100%

The redisClientAdapter's Publish/Close themselves remain 0% covered
since they trampoline to *redis.Client methods that need a real
Valkey server (covered by microvm-lifecycle).

Whole pkg/xtcp under dest_valkey: 81.4%

Lift the *kgo.Client.PollFetches surface into a 1-method kafkaFetcher
interface. *kgo.Client satisfies it; production unchanged.

New tests with a fakeFetcher that returns prescripted Fetches then
signals ctx-cancel:
  TestPollLoop_eachRecordClosureFires — drives the inner closure
    (records++; processRecord) that broker-bound tests couldn't reach
  TestPollLoop_fakeFetcherErrors      — exercises the fetches.Errors
    path with a non-empty error list

pollLoop:        61.5% → 100%
TOTAL:           81.4% → 93.0% ✓ above 90%

Same shape as D5: lift the *kgo.Client.PollFetches surface into a
1-method kafkaFetcher interface. *kgo.Client satisfies it; production
unchanged.

New test TestPollLoop_eachRecordClosureFires drives the closure that
broker-bound tests couldn't reach.

pollLoop:        80.0% → 100%
TOTAL:           86.0% → 94.7%

Add newKafkaProducerFn var (factory func) so tests can substitute a
fake-returning closure for kgo.NewClient. Production path goes through
newKafkaProducerReal which is unchanged from before.

New tests:
  TestNewKafkaDest_happy                 — full constructor path:
    register schema, get id, build (fake) producer, AllowRebalance,
    ping. Verifies fake.allowRebals + fake.pings increment.
  TestNewKafkaDest_factoryErr            — factory returns err →
    constructor wraps + returns 'kgo.NewClient' err
  TestNewKafkaDest_pingFailExhaustsRetries — fake fails all pings
    → constructor returns 'pingKafka' err

destinations_kafka.go:
  newKafkaDest 0% → 61.5%

The remaining 38.5% gap is the debugLevel>10 log statements + the
kgoMetrics setup which doesn't need testing. Whole pkg/xtcp under
dest_kafka still about 81% (the newKafkaProducerReal factory itself
counts as 0%-covered because tests never exercise it).

Add newValkeyClientFn factory var so tests can substitute a fake
valkeyPublisher for the production redisClientAdapter wrapping a
*redis.Client. Production path goes through newValkeyClientReal
(unchanged behavior).

New tests:
  TestValkeyDest_RedisClientAdapter_satisfiesIface
  TestNewValKeyDest_happy   — fake Ping succeeds, verify dest built
  TestNewValKeyDest_pingErr — fake Ping fails, verify constructor errs
  TestNewValKeyDest_debugLog — covers the debug-log gate

destinations_valkey.go:
  newValKeyDest       57.1% → 100%
  newValkeyClientReal new   → 100%
  Send/Ping/Close adapter methods remain partly uncovered since the
  adapter trampolines to *redis.Client which needs a real Valkey
  server (microvm-lifecycle covers them).

Same shape as D7/D8: add newNATSConnFn + newNSQProducerFn factory
vars so tests inject fakes instead of dialing real servers. Production
calls go through newNATSConnReal / newNSQProducerReal (unchanged
behavior).

New tests for each:
  TestNew{NATS,NSQ}Dest_happy        — full constructor path with fake
  TestNew{NATS,NSQ}Dest_factoryErr   — factory err → wrapped err
  TestNew{NATS,NSQ}Dest_debugLog     — debug-log gate

destinations_nats.go:
  newNATSDest        60% → 100%
  newNATSConnReal    new → 100%
  All other funcs    already 100% from D2

destinations_nsq.go:
  newNSQDest         60% → 100%
  newNSQProducerReal new → 100%
  All other funcs    already 100% from D3

Combined pkg/xtcp coverage (all dest flavors): 80.2% → 82.0%.

Drive the full netlinkerSyscall loop using a real socketpair with
SO_RCVTIMEO set to 50ms so Recvfrom periodically returns and the loop
polls ctx (mirrors what production setSocketTimeoutViaSyscall does).
The Deserialize call rejects the garbage payload + bumps the
ParseNLPacket err counter, then ctx cancel breaks the loop.

New tests in pkg/xtcp/netlinker_loop_test.go:
  TestNetlinkerSyscall_loopDrivesViaSocketpair — full loop iteration
    covering recv → log → metrics → capture-skip → Deserialize-err
    → continue
  TestNetlinkerSyscall_immediateCancelExitsCleanly — pre-canceled ctx
  TestNetlinkerSyscall_captureBranchFires — WriteFiles>0 path (real
    CapturePath; verifies the captureToFileIfEnabled-true branch
    executes inside the loop)
  TestNetlinkerSyscall_earlyExit (already passed; minor smoke)

Per-function coverage:
  netlinkerSyscall  40.7% → 96.3%

A drive-by helper TestNewKafkaProducerReal_returnsKgoClient covers
the production kgo.NewClient factory (was 0% in D7).

Whole pkg/xtcp under all dest flavors: 82.0% → 83.0%.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>